 /*
  * $Header: /cvshome/build/org.osgi.service.wireadmin/src/org/osgi/service/wireadmin/Envelope.java,v 1.8 2006/06/16 16:31:43 hargrave Exp $
  *
  * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.osgi.service.wireadmin;

 /**
  * Identifies a contained value.
  *
  * An <code>Envelope</code> object combines a status value, an identification
  * object and a scope name. The <code>Envelope</code> object allows the use of
  * standard Java types when a Producer service can produce more than one kind of
  * object. The <code>Envelope</code> object allows the Consumer service to
  * recognize the kind of object that is received. For example, a door lock could
  * be represented by a <code>Boolean</code> object. If the <code>Producer</code>
  * service would send such a <code>Boolean</code> object, then the Consumer
  * service would not know what door the <code>Boolean</code> object represented.
  * The <code>Envelope</code> object contains an identification object so the
  * Consumer service can discriminate between different kinds of values. The
  * identification object may be a simple <code>String</code> object, but it can
  * also be a domain specific object that is mutually agreed by the Producer and
  * the Consumer service. This object can then contain relevant information that
  * makes the identification easier.
  * <p>
  * The scope name of the envelope is used for security. The Wire object must
  * verify that any <code>Envelope</code> object send through the <code>update</code>
  * method or coming from the <code>poll</code> method has a scope name that
  * matches the permissions of both the Producer service and the Consumer service
  * involved. The wireadmin package also contains a class <code>BasicEnvelope</code>
  * that implements the methods of this interface.
  *
  * @see WirePermission
  * @see BasicEnvelope
  *
  * @version $Revision: 1.8 $
  */
 public interface Envelope {
     /**
      * Return the value associated with this <code>Envelope</code> object.
      *
      * @return the value of the status item, or <code>null</code> when no item is
      * associated with this object.
      */
     public Object getValue();

     /**
      * Return the identification of this <code>Envelope</code> object.
      *
      * An identification may be of any Java type. The type must be mutually
      * agreed between the Consumer and Producer services.
      *
      * @return an object which identifies the status item in the address space
      * of the composite producer, must not be null.
      */
     public Object getIdentification();

     /**
      * Return the scope name of this <code>Envelope</code> object.
      *
      * Scope names are used to restrict the communication between the Producer
      * and Consumer services. Only <code>Envelopes</code> objects with a scope
      * name that is permitted for the Producer and the Consumer services must be
      * passed through a <code>Wire</code> object.
      *
      * @return the security scope for the status item, must not be null.
      */
     public String getScope();
 }

